feat: remote environments for SSH and Docker execution targets (phase 1: creation-time binding) - #4062

…repo-wide

Runtime->Environment across agent-core-v2, remote-exec, node-sdk,
kap-server, klient, acp-server, apps/kimi-code, apps/vis, apps/kimi-inspect
and the en/zh docs: the Runtime interface and its family (registry, lease,
binding, provider, unit host, workspace view), the [environments] config
section and .kimi-code/environments.toml, the /environment slash command and
--environment flag, the session environment REST/WS surface, and the SDK
session methods. The Runtime.environment field becomes host. Durable wire
surfaces break clean with no shims (the feature is experimental): the
environment.set_binding event type, environment.status.changed, the
runtimeBinding/runtime.binding state keys, the tui.toml status-line slot id,
and the klient IPC service key. Unrelated runtime concepts (goal actor enum,
MCP runtime names, model runtime config, worker runtimes, kimiCu, the
remote_runtime experimental flag) keep their names.

Rename the leftovers the round-1 review enumerated: the REST error
string and OpenAPI descriptions on the environment surface, the
environment-provider error strings, the remaining type names
(EnvironmentReadStreamSource, EnvironmentStdioTransport, the test wire
types), execution-target locals and test fake variables, and revert the
session-status variable to runtimeStatus to match its family.

Rename the createGeneration locals to environment (declaration + usages),
switch three lease-value longhands to shorthand, and retitle the kap-server
environment route describe block.

Rename the last batch of runtime-flavored factories, locals, params, and
test titles across the test tree to environment (registries, binding,
program, session, workspace, plan, media, kap-server, node-sdk, acp-server,
remote-exec), switch the remaining lease-value longhands to shorthand, and
keep the unrelated runtime zones (actor runtime, worker runtimes,
FiberRuntime, kimiCu, MCP runtime names, model runtime config) intact.

Remove the remote_runtime experimental flag entirely: the flag definition,
its KIMI_CODE_EXPERIMENTAL_REMOTE_RUNTIME env var, and every enabled() gate
across the engine (provider attach, session manager, agent binding, workspace
roots), the remote-exec provider, the node-sdk session surface, the kap-server
REST routes, and the TUI (slash command, footer slot, mention suggester,
feedback attachment). Remote environments are now unconditionally on.

Also register the environment.status.changed event in the kap-server zod
agentEventSchema so it enters the AsyncAPI contract, document the feature as
stable in the en+zh guides and references (dropping flag instructions and
experimental labels), complete the server-api environment endpoint docs with
the declare route, and fold the five pending experimental changesets and the
rename changeset into a single graduation changeset — the feature had no
prior release, so this is its first user-facing announcement.

The trust prompt only listed gated MCP servers even though the SDK already
returns gatedEnvironments with each declaration's full launch command line.
An untrusted repo could declare launchers in .kimi-code/environments.toml
and the prompt never showed what the user authorized. Render the launchers
like the MCP targets, with the same control-character sanitization.

The remote-exec provider re-resolved declarations only on config-section
changes and the project file watch. A workspace materialized while
untrusted kept project environments unregistered after the user accepted
trust, and a project default then seeded sessions with an id absent from
the registry.

Program now re-fires the local generation's trust changes on a stable
onDidChangeTrust event (re-subscribed across generation rebuilds), the
manager passes it through EnvironmentProviderContext, and the provider
reconciles on every flip in both directions.

The node-sdk and kap-server each carried an identical unguarded
read-merge-write of .kimi-code/environments.toml, so two concurrent adds
(or one via REST plus one via SDK) read the same snapshot and the last
write silently dropped the other entry.

Consolidate the helper into agent-core-v2 with a per-path promise-chain
mutex so updates serialize per file; both call sites now share it.

…ect-local config

Two graduation-blocking finds from the live smoke:

- The native print path bootstrapped the engine without ever attaching the
  remote-exec provider, so declared environments never registered and
  kimi -p --environment <id> always failed 'environment does not exist'.
  Attach the provider after bootstrap, mirroring the SDK client.
- FileProjectLocalConfigService treated only Node errnos as path-missing,
  so a remote HostFsError (no Node-style cause) for a missing
  .kimi-code/local.toml crashed session startup with storage.io_failed
  instead of reading as no project-local config. Accept the fs-domain
  not-found codes too.

The flag was parsed and honored in print mode, but the interactive TUI's
startup options never carried it and the lazy first session was created
without environmentId — kimi --environment <id> silently started a local
session. Thread it through TUIStartupOptions into the lazy creation path
with the same first-session-only consumption as --agent.

…n the busy frame

Container.invalidate() only clears child render caches; it never schedules
a repaint, so a switch/reconnect/declare failure that resolved after the
keypress cycle left the dialog stuck on 'Connecting…' until the next key.
Thread requestRender through the three environment dialogs' options (the
MigrationScreenComponent precedent), expose it on SlashCommandHost, and
invoke it after every async setBusy/showError/setOptions. Also sweeps the
stale '(experimental remote environment)' header comments.

Undo across an environment switch left the binding on the switched-to
environment: the binding service's onDidRestore hook runs only on the
first restore (didRunRestoreHooks), so a rerun restore after an undo
rebuilt the environmentBindingKey projection at the cut point but never
re-applied it to the live binding — and any path falling back to
peekPersistedBinding would re-read the untruncated wire log and re-apply
the newest (post-switch) binding, which is right for resume and wrong
for undo.

Register an AgentConversationUndoParticipant in the binding service: it
reads the cut-point projection (or the seed binding when the cut predates
the first binding event) and re-applies it with the full side effects —
session workDir, background reconnect, environment reminder on a machine
identity change, and the onDidChange fire so the footer slot follows.
The resume path (hook + peek fallback) is untouched and the two paths
cannot fight: the hook is once-per-dispatcher, the participant runs only
on undo. The mechanism is event-general, so M49's model-initiated
EnvironmentSetBinding ops ride the same revert path.

The dialogs now invoke the host's requestRender after async state changes;
the command-flow test's host mock predates the method and crashed the
switch/reconnect/add flows silently.

- Drop the last two stale '(experimental remote environment)' comments
  (commands/environment.ts header, footer environment slot).
- Remove the dead ENVIRONMENT_UNAVAILABLE entry from the declare route's
  OpenAPI errors block — nothing in the declare handler throws it.
- Brace the two new void-expression arrows (program.ts trust re-fire,
  remoteEnvironmentProvider trust listener) and drop the four unnecessary
  WireRecord assertions in the undo-test stub, restoring the lint warning
  count to baseline.
- Correct the switch endpoint's cwd docs (en+zh): non-local switches
  require cwd (40001 when missing); the entry's defaultCwd applies only
  in the createSession seed path.

Four no-confusing-void-expression warnings from the Bug A wiring — same
shape as the program.ts and remoteEnvironmentProvider.ts arrows braced in
the previous sweep.

The remote-environment footer slot rendered the connecting status as
static warning-colored text. Reuse the shared braille frame set and
80ms interval (the same set the thinking indicator uses) to tick a
spinner ahead of the environment id.

The timer is strictly bounded to the connecting status: it starts when
the slot enters connecting and stops the moment the status moves on
(or the footer is disposed), repainting each frame through the
standard onRefresh path. Other statuses render exactly as before and
the local environment still renders nothing.

…stubs

- merge the glob/grep rgUnavailableGuidance suites into one parameterized suite
- consolidate environmentBindingService setup/undoSetup onto shared stub builders
- unify sessionManager remote-wiring setups (remoteWiringSetup/localRegistry/workspacesFor)
- add test/environment/stubs.ts (stubAgentEnvironment/fakeEnvironment/connectableEnvironment) and adopt across tool, binding, registry, view, and sessionManager suites
- share recordingAppendFs across task persistence and output-access suites
- hoist EnvironmentRegistry construction in environmentRegistry.test.ts
- extract resolve() helper in environmentDeclarations.test.ts and programWorkspace/noopLogger reuse in program.test.ts

- share expectCurrentBinding in agentLifecycle remote binding tests
- extract stubHostProcess into test/os/stubs.ts for gitContext/spawn suites
- wrap stubPlanEnvironment with the shared stubAgentEnvironment builder
- fold the remote plans-dir mkdir assertion into the stores-plan test
- route sessionInit environment stub through stubAgentEnvironment
- share failingRunner across externalHooksRunner error-reporting tests
- extract registerHookTestServices for the externalHooks integration tests
- extract connectingReadExecution in read.test.ts
- extract provideHost in environmentUnitHost.test.ts
- dedup the image-originals fake fs builders
- share resolverFor in fsService.test.ts and stubRgProbe across rgLocator suites

…m rule)

Each deleted test pinned a behavior already covered by a surviving test on the
same code path with the same inputs and oracle; every seam (DI registration,
lifecycle wiring, reconnect/reroot orchestration) keeps its own pin:

- binding 'acquires a ready environment without waiting on a readiness signal':
  survives in environmentRegistry 'acquires a ready environment through
  acquireWhenReady without waiting' (same registry path; strengthened with a
  never-resolving whenReady) + binding 'waits for the in-flight connect'
  (pins the non-turn service delegation of the same method)
- binding 'rejects with the connect reason when the in-flight connect fails':
  survives in environmentRegistry 'rejects acquireWhenReady with the connect
  failure reason when the readiness signal rejects' (same path, same
  rejects.toBe(failure) oracle)
- binding 'keeps the immediate environment.unavailable error for a plainly
  disconnected environment': survives in environmentRegistry 'keeps the
  immediate unavailable error on a plainly disconnected environment' (same
  path, adds the missing-env case)
- sessionManager 'aborts creation when the configured default environment
  fails to connect': survives in sessionManager 'aborts creation when the
  environment connect fails' (same create->connect-failure path, stronger
  oracle) + 'connects the configured default environment before creating the
  session' (default resolution)
- binding 'does not reconnect a replayed remote binding for the main agent':
  survives in agentLifecycle 'restores the main agent binding without the
  binding service reconnecting it' (same restore-hook path through the
  lifecycle DI seam, same no-connect oracle)
- binding 'background-reconnects and reroots a replayed remote binding for
  non-main agents': survives in agentLifecycle 'restores a remote-bound
  subagent from wire records and background-reconnects' (same path through
  the lifecycle DI seam, same connectCalls/rerootCalls oracles)
- binding 'keeps a gone declaration bound after reseed and fails explicitly
  at use': survives in agentLifecycle 'keeps a restored gone environment
  declaration bound and fails explicitly at use' (same behavior through the
  lifecycle DI seam) + environmentRegistry 'does not fallback when a
  environment is missing' (not_found at the registry layer)

…onment

…ng suites

- read-media environmentFor, apply-profile mappedEnvironmentService, and the
  agentsMdReminder inline service now wrap stubAgentEnvironment (with an
  isAvailable/onDidChange option)
- hoist the repeated GlobTool construction into beforeEach in glob.test.ts

the 23 identical manager.dispose()/registry.dispose() pairs in the remote
environment wiring describe collapse into one afterEach, which also disposes
on failure paths the inline calls never reached

…session use

ISessionManager.create again rejects a missing or non-directory workDir with fs.path_not_found for local bindings; remote bindings keep deferred root validation, and createOrTouch stays lenient.

SDKRpcClientV2 awaits the remote environment provider attach before create/resume/fork/reload and temporary resume, so declared or persisted remote environments no longer report unavailable or fall back to a local controller based on registration timing.

…ding service

…cation

…sion meta